

    \filetitle{plotpred}{Visualize multi-step-ahead predictions}{tseries/plotpred}

	\paragraph{Syntax}

\begin{verbatim}
[H1,H2,H3] = plotpred(X,Y,...)
[H1,H2,H3] = plotpred(Ax,X,Y,...)
[H1,H2,H3] = plotpred(Ax,Range,X,Y,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{X} {[} tseries {]} - Input data with time series observations.
\item
  \texttt{Y} {[} tseries {]} - Prediction data arranged as described
  below; the prediction data returned from a Kalman filter can be used,
  see Example below.
\item
  \texttt{Ax} {[} numeric {]} - Handle to axes object in which the data
  will be plotted.
\item
  \texttt{Range} {[} numeric \textbar{} Inf {]} - Date range on which
  the input data will be plotted.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\item
  \texttt{H1} {[} numeric {]} - Handles to a line object showing the
  time series observations (the first column, \texttt{X}, in the input
  data).
\item
  \texttt{H2} {[} numeric {]} - Handles to line objects showing the
  Kalman filter predictions (the second and further columns, \texttt{Y},
  in the input data).
\item
  \texttt{H3} {[} numeric {]} - Handles to one-point line objects
  displaying a marker at the start of each line.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}connect=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Connect the
  prediction lines, \texttt{Y}, with the corresponding observation in
  \texttt{X}.
\item
  \texttt{\textquotesingle{}firstMarker=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}none\textquotesingle{}}} \textbar{}
  char {]} - Type of marker displayed at the start of each prediction
  line.
\item
  \texttt{\textquotesingle{}showNaNLines=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Show or remove
  lines with whose starting points are NaN (missing observations).
\end{itemize}

See help on \href{tseries/plot}{\texttt{plot}} and on the built-in
function \texttt{plot} for options available.

\paragraph{Description}

The input data \texttt{Y} need to be a multicolumn time series (tseries
object), with one-step-ahead predictions \texttt{x(t\textbar{}t-1)} in
the first column, two-step-ahead predictions \texttt{x(t\textbar{}t-2)}
in the second column, and so on. Note the timing assumptions.

If \texttt{x1} is a series with one-step-ahead predictions
\texttt{x(t+1\textbar{}t)}, \texttt{x2} is a series with two-step-ahead
predictions \texttt{x(t+2\textbar{}t)}, and so on, while \texttt{x} is a
series with the actual observations \texttt{x(t)}, the following command
will create a time series that can be then passed into
\texttt{plotpred(\ )}:

\begin{verbatim}
p = [ x1{-1}, x2{-2}, ..., xn{-n} ];
plotpred(x, p);
\end{verbatim}

\paragraph{Example}

The \texttt{plotpred(\ )} function can be used with prediction-step data
returned from a Kalman filter, \href{model/filter}{\texttt{filter}}. The
prediction-step data need to be specifically requested using the
\texttt{\textquotesingle{}output=\textquotesingle{}} option (as they are
not included in the output database by default), with the prediction
horizon assigned in the
\texttt{\textquotesingle{}ahead=\textquotesingle{}} option (the horizon
is \texttt{1} by default):

\begin{verbatim}
[~, g] = filter(m, d, startDate:endDate, ...
    'output=', 'pred', 'meanOnly=', true, 'ahead=', 8); 

figure( );
plotpred(startdate:enddate, d.x, g.pred.x); 
\end{verbatim}


